home *** CD-ROM | disk | FTP | other *** search
/ Belgian Amiga Club - ADF Collection / BS1 part 19.zip / BS1 part 19 / BBC emulator pre-release.adf / Documentation < prev    next >
Text File  |  1988-07-19  |  26KB  |  715 lines
  1. *****************************************************************************
  2.  
  3. AMIGA BBCEMULATOR DRAFT DOCUMENTATION                   VERSION 0.95
  4.  
  5. COMMODORE BUSINESS MACHINES (UK) LTD.                   ARIADNE SOFTWARE LTD.
  6.  
  7. (C) Copyright 1988 CBM (UK) Ltd.  All rights reserved.
  8.  
  9. Commodore Business Machines (UK) Ltd.            Ariadne Software Ltd.
  10. Commodore House,                    273 Kensal Road,
  11. The Switchback,                        LONDON
  12. Gardner Road,                        W10 5DB
  13. Maidenhead,
  14. Berks SL6 7XA                        01 960 0203
  15.  
  16. 0628 770088
  17.  
  18. *****************************************************************************
  19.  
  20. CIRCULATION      : CONFIDENTIAL within the terms of the CBM (UK) agreement.
  21.                    Not to be copied or redistributed in any form without
  22.                    the permission of CBM (UK) Ltd.
  23.  
  24. DOCUMENT EDITION : Revision 3, 16th November 1988.  This revision by DaveP.
  25.  
  26. *****************************************************************************
  27.  
  28. AMIGA BBCEMULATOR VERSION 0.95 - DRAFT DOCUMENTATION
  29.  
  30. *****************************************************************************
  31.  
  32. Introduction
  33. ~~~~~~~~~~~~
  34. The Amiga BBCEmulator is a program which will turn part of your Amiga into
  35. something rather, but not exactly, like a BBC Model B with BASIC 2 and DFS.
  36. It runs as a PROCESS on its own screen within the Amiga multi-tasking
  37. operating system; thus you can run it AT THE SAME TIME as Amiga programs
  38. like editors and Workbench accessories.  This means that if you have an
  39. Amiga 2000 with Bridgecard and a reasonable amount of memory, you can run
  40. BBC applications, PC applications, and native Amiga applications at the same
  41. time if you so wish, with easy transfer of data between the different
  42. environments.  You can even run several BBCEmulators at once if you want to!
  43.  
  44. Our principal objective in creating the BBCEmulator has been to run existing
  45. education software, written in BBC BASIC or in a mixture of BASIC and
  46. 6502 assembler, as well as possible - WITHOUT killing off the Amiga's native
  47. advantages such as split screens and multi-tasking.  Speed of execution of
  48. BBC BASIC is very good - we have clocked speeds of over seven times faster
  49. than the original on some programs.  We can also run programs written
  50. entirely in 6502 assembler - however, since we are having to emulate
  51. 6502 (RISC chip) hardware in 68000 (CISC chip) software, this isn't nearly
  52. as fast, and isn't recommended for serious applications.
  53.  
  54. Emulator strategy has been to create a "bridge" from the BBC operating system
  55. through to the Amiga's operating environment.  This means that we can run
  56. nearly all "legal" BBC software which uses BASIC and the OS - ie software
  57. which will run on things like 6502 second processors.  We cannot however run
  58. "illegal" software that dodges the OS and goes direct to BBC screen memory
  59. or to the hardware.  In practice, this means that we can run nearly all
  60. educational programs written in BASIC or a mixture of BASIC and assembler,
  61. but not things like arcade-style games - sorry!
  62.  
  63. Principal components of the BBCEmulator software are as follows:
  64.  
  65. Beebos:    A "bridge" from the BBC operating system through to the Amiga
  66.     graphics libraries, maths libraries, etc.
  67.  
  68. DFS:    "Disk furtling system" - a bridge from DFS through to AmigaDOS.
  69.  
  70. BASIC:    A new implementation of BBC BASIC, re-coded from scratch in 68000
  71.     assembler, but with the aim of being as compatible as possible with
  72.     BBC BASIC 2 (except for the bugs!).  A VERY fast implementation,
  73.     though we say it ourselves.
  74.  
  75. 6502:    An emulation of the 6502 chip, written in 68000 assembler - enables
  76.     programs which call assembler subroutines to work properly, though
  77.     not as fast as the original.
  78.  
  79. Other elements in the software are a "CLI environment" entered by *GO, and
  80. a simple 6502 monitor, entered by *MONITOR.
  81.  
  82. This documentation assumes basic familiarity with the Amiga environment as
  83. explained in the User Guide; it also assumes familiarity with the BBC
  84. computer.  Material needing a more advanced understanding of the Amiga
  85. system are flagged as "Techy notes" - ignore these if you want to.
  86.  
  87. Getting started
  88. ~~~~~~~~~~~~~~~
  89. You should first backup the BBCEmulator disk and put the original in a safe
  90. place - you MAY NOT however make copies except for your own use on your
  91. own machine, except by special agreement with Commodore.
  92.  
  93. To get started in the BBCEmulator, you should insert your copy of the master
  94. disk, open the disk by double-clicking on its Icon, then invoke the
  95. BBCEmulator by double clicking on the Icon.  The disks will turn for
  96. a bit while it fetches various bits and pieces; if you a running on a single
  97. drive system you may be prompted to reinsert your Workbench for the
  98. BBCEmulator to load certain Amiga system libraries.  You should then find
  99. yourself in the BBCEmulator.
  100.  
  101. Note that the BBCEmulator expects to find BASIC in the same drawer as itself -
  102. so if you copy the program somewhere else, you should move BASIC as
  103. well.  If it can't find BASIC you will find yourself in the CLI environment, 
  104. the prompt for which is a star '*'.
  105.  
  106. To PAUSE the BBCEmulator, perform a mouse-click anywhere in the BBCEmulator
  107. screen; this will also give you an Amiga "drag bar" at the top of the screen,
  108. which can be used to pull it up and down, or rearrange it relative to the
  109. Workbench and any other screens you may have open.  With the BBCEmulator in
  110. pause mode, it is possible to run various accessories from the Amiga
  111. Workbench and Extras disk, including Palette and GraphicDump utilities.
  112. To get rid of the drag bar and get the BBCEmulator running again, click again
  113. anywhere in the BBCEmulator screen below the drag bar.
  114.  
  115. To EXIT the BBCEmulator, enter the special command:
  116.  
  117.     *CLOSEDOWN
  118.  
  119. TECHY NOTE:  In order to run properly, the BBCEmulator needs to be on a PAL
  120. Amiga with at least 300K free memory, with a 68000 (not 68010 etc)
  121. processor.  It also expects to find mathstrans.library in its LIBS:
  122. directory.  If any of these conditions aren't met, it will fail to open.
  123.  
  124. The keyboard
  125. ~~~~~~~~~~~~
  126. The first thing you will probably want to do on entering the BBCEmulator is 
  127. to press CAPS LOCK - this is in order to talk to BASIC sensibly.
  128.  
  129. The BBCEmulator pays attention to your Keymap and Preferences settings as
  130. determined by your Amiga Workbench.  Note that Preferences determine things
  131. like key repeat delays - things like *FX 11 and 12 have no effect.  The
  132. numeric keypad works as would be expected.
  133.  
  134. Certain keys are "stolen" by the BBCEmulator to have special effects.  These
  135. are as follows:
  136.  
  137.     Function keys     - as BBC function keys; F10 used for F0
  138.     Cursor keys     - as BBC cursor keys for copy key editing, etc
  139.     Backspace     - acts like BBC DELETE
  140.     Del         - acts like copy key
  141.     Help        - acts like BREAK
  142.  
  143. Note that some protection has been applied to the BREAK facility - to BREAK
  144. it is necessary to HOLD DOWN LEFT AMIGA (CBM key on some A500s) THEN PRESS
  145. HELP.  This performs a "warm boot" like BBC BREAK; you can also perform a
  146. "cold boot" by HOLDING DOWN CTRL AND LEFT AMIGA THEN PRESSING HELP.  Cold
  147. boot differs from warm boot in that it resets the programmable function keys,
  148. and resets the DFS - note that this involves a few seconds pause for disk
  149. activity if you are running on floppies.
  150.  
  151. Graphics modes
  152. ~~~~~~~~~~~~~~
  153. The BBCEmulator supports the following graphics modes:
  154.  
  155.     0    640 x 256    2 colours    80x32
  156.     1    320 x 256    4 colours    40x32
  157.     2    320 x 256      16 colours    20x32
  158.     3    text only    2 colours    80x25
  159.     4    320 x 256    2 colours    40x32
  160.     5    320 x 256    4 colours    20x32
  161.     6    text only    2 colours    40x25
  162.     7        Teletext display    40x25
  163.  
  164. Note that in modes 2 and 5 the horizontal resolution is actually double
  165. the original - which doesn't seem to be a problem.  The double width
  166. (20 column) characters are rendered accurately however.
  167.  
  168. The BBC's Teletext (Mode 7) display is emulated in software in the
  169. BBCEmulator.  Mode 7 is the fastest mode on the BBC, but the slowest
  170. mode on the BBCEmulator.  This is because we are having to emulate character-
  171. based hardware in pixel-based software - think of a very skilled painter
  172. trying to create text as fast as a crummy old typewriter.
  173.  
  174. The speed of BBCEmulator Mode 7 should be more than fast enough for all
  175. practical application purposes; however it is not recommended for program
  176. editing.  For this reason, the "power up default" for the BBCEmulator has
  177. been set to Mode 6.
  178.  
  179. Note that Teletext HOLD and RELEASE graphics are not available in version
  180. 0.95 of the BBCEmulator.
  181.  
  182. Vdu drivers
  183. ~~~~~~~~~~~
  184. The following VDU calls are supported:
  185.  
  186.     VDU 0    No effect
  187.     VDU 1    NOT YET AVAILABLE
  188.     VDU 2    NOT YET AVAILABLE
  189.     VDU 3    NOT YET AVAILABLE
  190.     VDU 4    Text at text cursor
  191.     VDU 5    Text at graphics cursor
  192.     VDU 6    NOT YET AVAILABLE
  193.     VDU 7    Make a beep
  194.     VDU 8    Backspace cursor
  195.     VDU 9    Forwardspace cursor
  196.     VDU 10    Move down cursor
  197.     VDU 11    Move up cursor
  198.     VDU 12  Clear text window
  199.     VDU 13  Carriage return
  200.     VDU 14    Page mode on
  201.     VDU 15    Page mode off
  202.     VDU 16    Clear graphics window
  203.     VDU 17    Change text colour
  204.     VDU 18    Change graphics colour - GCOL 0 ONLY
  205.     VDU 19    Change colour palette
  206.     VDU 20    Restore default palette
  207.     VDU 21    NOT YET AVAILABLE
  208.     VDU 22    MODE
  209.     VDU 23    User-defined character
  210.     VDU 24    NOT YET AVAILABLE
  211.     VDU 25    PLOT 
  212.     VDU 26    Default windows
  213.     VDU 27    No effect
  214.     VDU 28    Define text window
  215.     VDU 29    Define graphics origin
  216.     VDU 30    Home cursor
  217.     VDU 31    Move cursor
  218.     VDU 127    Backspace and delete
  219.  
  220. Note that the BBCEmulator character set is always fully "exploded" - meaning
  221. that any character from 32 to 126 and 128 to 255 can be redefined using
  222. VDU 23.  VDU 23,1 to switch cursor on/off is supported, as are various
  223. variations on VDU 23,0.  Other uses of VDU 23,0 are NOT supported however.
  224.  
  225. Note also that GCOL modes 1 to 4 are not available from the Amiga
  226. graphics library, and are therefore not supported.
  227.  
  228. Operating system commands
  229. ~~~~~~~~~~~~~~~~~~~~~~~~~
  230. The following standard commands are supported via the BBCEmulator CLI:
  231.  
  232.     *CAT <drive>
  233.     *BASIC 
  234.     *CODE [X,Y]            -    NOT YET IMPLEMENTED
  235.     *EXEC <file>
  236.     *FX A [,X,Y]
  237.     *GO [<address>]
  238.     *HELP [<subject>]
  239.     *KEY N <string>
  240.     *LOAD <file> [<address>]
  241.     *LINE <text>            -    NOT YET IMPLEMENTED
  242.     *MOTOR 0/1            -    NO EFFECT
  243.     *OPT X,Y            -    OPT 4 ONLY
  244.     *RUN <file>
  245.     *ROM                 -    NO EFFECT
  246.     *SAVE <file><start><end/+ln>[<x>][<ld>]
  247.     *SPOOL <file>
  248.     *TAPE                 -    NO EFFECT
  249.     *TV X,Y                -    NO EFFECT
  250.  
  251. *GO by itself will enter a special "CLIPrompt" environment, with a '*' 
  252. prompt; to get back to BASIC use '*BASIC'.
  253.  
  254. A number of special commands are also supported; these are discussed
  255. elsewhere in this document.
  256.  
  257.     *AEXEC [<file>]
  258.     *ASPOOL [<file>]
  259.     *CLOSEDOWN 
  260.     *CONNECT [<baud>]
  261.     *FORCECLOSE 
  262.     *ICOPY <source> <dest> <files>
  263.     *IMPORT <source> <dest>
  264.     *MONITOR 
  265.     *SEVER 
  266.  
  267. ASPOOL and AEXEC
  268. ~~~~~~~~~~~~~~~~
  269. *ASPOOL and *AEXEC are like their DFS equivalents, but take an AmigaDOS
  270. path-name as a parameter, and work in AmigaDOS compatible format. They 
  271. are used to transfer text files between the BBCEmulator and the standard
  272. Amiga environments.  For example, to export a program Eric to the Amiga RAM
  273. disk in AmigaDOS compatible format, use
  274.  
  275.     *ASPOOL RAM:Eric
  276.     LIST
  277.     *ASPOOL
  278.  
  279. This file could then be edited using an Amiga editor such as MicroEmacs; it
  280. could then by imported back again by
  281.  
  282.     NEW
  283.     *AEXEC RAM:Eric
  284.  
  285. Printer redirection by CTRL-B is not yet supported explicitly within the
  286. BBCEmulator.  For the time being, a good way to get a program listing is
  287.  
  288.     *ASPOOL PRT:
  289.     LIST
  290.     *ASPOOL
  291.  
  292. Alternatively, you might prefer to ASPOOL to a RAM: file as above, start a
  293. new CLI on the Workbench, then on this CLI enter
  294.  
  295.     COPY RAM:Eric PRT:
  296.  
  297. This will allow you to print as a background process, without holding up the
  298. BBCEmulator.
  299.  
  300. If you have Workbench 1.3, you may wish to experiment communicating directly
  301. between BBCEmulator and other Amiga processes by means of "pipes".  For
  302. example, try pulling down the BBCEmulator in front of an AmigaDOS CLI on
  303. Workbench, load a BASIC program in BBCEmulator, then type
  304.  
  305.     TYPE PIPE:A        in the AmigaDOS CLI
  306.  
  307. then    *ASPOOL PIPE:A        in the BBCEmulator
  308.     LIST
  309.     *ASPOOL
  310.  
  311. *ASPOOL, *AEXEC and Pipes can be used to establish direct communication
  312. between two copies of the BBCEmulator - if anyone can think of any possible 
  313. use for this!
  314.  
  315. Disk Furtling System
  316. ~~~~~~~~~~~~~~~~~~~~
  317. The Disk Furtling System allows an Amiga "drawer" or directory to appear
  318. as a complete DFS disk to the BBCEmulator.  Silly DFS limitations like 31
  319. files per drawer have been retained for reasons of strict compatibility -
  320. tell us if you think we should increase this - however, it is possible to
  321. have as many DFS drawers as you like on any Amiga disk.
  322.  
  323. The BBCEmulator startup default is to assign DFS drives 0 to 3 to Amiga
  324. drawers Drive0, Drive1, Drive2 and Drive3.  This can be changed later using
  325. *ASSIGN - eg to assign DFS drive 0 to the Amiga RAM disk use
  326.  
  327.     *ASSIGN 0 RAM:
  328.  
  329. or, more generally,
  330.  
  331.     *ASSIGN <DFS drive number> <AmigaDOS path name>
  332.  
  333. The DFS expects to find its files in the form $.ERIC (<directory>.<name>),
  334. and its catalog information in a special file DFSCat.  If you try to assign
  335. to a drawer without a DFSCat you will get a warning message "No catalog";
  336. if you try to access a drive which has not been assigned or which has no
  337. catalog you will get an error message "Drive not valid".  If you forget where
  338. a drive is assigned, you can find out by just typing
  339.  
  340.     *ASSIGN <drive>
  341.  
  342. It is possible to access a DFS drawer from outside the BBCEmulator -
  343. eg from the Amiga CLI, or from a utility program such as CLIMate.  If you
  344. have been making changes in the drawer from outside the BBCEmulator, then you
  345. can build a new DFSCat by using the command
  346.  
  347.     *MAKE <drive>
  348.  
  349. eg to get a valid DFS "disk" in the Amiga RAM disk, you should
  350.  
  351.     *ASSIGN 0 RAM:
  352.     *MAKE 0
  353.  
  354. If any files of the form <dir>.<name> are found in the specified directory,
  355. MAKE will prompt with the filename; you can then enter a (hex) load address
  356. followed optionally by an execution address, or just press return if this
  357. has no relevance.
  358.  
  359. If you have added or deleted files to an existing DFS drawer from outside
  360. the BBCEmulator, then you can update the DFSCat to reflect just the changes
  361. made by
  362.  
  363.     *REMAKE <drive>
  364.  
  365. Standard DFS and UTILS commands supported are:
  366.  
  367.     *ACCESS <files> [L]
  368.     *COMPACT <drive>
  369.     *COPY <sdrive> <ddrive> <files>
  370.     *DELETE <file>
  371.     *DIR <dir>
  372.     *DRIVE <drive>
  373.     *ENABLE 
  374.     *INFO <files>
  375.     *LIB <lib>
  376.     *RENAME <from> <to>
  377.     *TITLE <name>
  378.  
  379.     *DISC 
  380.     *DISK 
  381.     *BUILD <file>
  382.     *DUMP <file>
  383.     *LIST <file>
  384.     *TYPE <file>
  385.  
  386. *BACKUP, *DESTROY and *WIPE are not supported - it is easier to perform
  387. this sort of operation from the Amiga CLI (or CLIMate etc), then to fix
  388. up the DFS directory using *REMAKE.   Individual DFS Drawers can be copied
  389. from disk to disk by dragging the "disk drive" Icons; complete BBCEmulator
  390. disks can be backed up by dragging the Icons in the normal manner.
  391.  
  392. BBCEmulator non-standard DFS commands are as follows:
  393.  
  394.     *ASSIGN <drive> [<path>]
  395.     *BOOT [<drive>]
  396.     *MAKE <drive>
  397.     *REMAKE <drive>
  398.  
  399. Note that the characters $ and / have special meanings to AmigaDOS - in
  400. order to avoid confusing the system, these characters appear as pound signs
  401. (Amiga ALT-L) and as broken vertical bars (ALT-I) in AmigaDOS directories
  402. respectively.
  403.  
  404. Import facilities
  405. ~~~~~~~~~~~~~~~~~
  406. The BBCEmulator contains special commands to allow existing files to be
  407. transferred from a BBC with DFS, by means of a serial cable.  PLEASE
  408. NOTE that this is intended to allow you to transfer your own files, and
  409. public domain software; using it to transfer commercial software is almost
  410. certainly a breach of licencing agreement - in exactly the same way as making
  411. unauthorized copies by any other mechanism.  The amount of piracy in
  412. education is increasingly encouraging anyone any good at writing educational
  413. software to pack it in and do something else, so please don't add to the
  414. problem - we mean this!
  415.  
  416. In order to transfer files which you are legitimately entitled to, you will
  417. need a serial cable to run between the BBC's RS423 and the Amiga's RS232
  418. ports.  A standard "null-modem" cable (ie one in which data in and out are
  419. crossed, NOT a "modem" cable where they go straight through) should do fine;
  420. if you don't have one you will need to have a cable made up as follows:
  421.  
  422.     BBC data in     pin A    to    Amiga TXD    pin 2
  423.     BBC data out     pin B    to    Amiga RXD    pin 3
  424.     BBC 0V      pin C    to    Amiga system 0V pin 7
  425.  
  426.     BBC CTS        pin D    to    BBC RTS        pin E
  427.  
  428. Code transfer is supported via the following commands:
  429.  
  430.     *CONNECT
  431.     *SEVER
  432.     *IMPORT
  433.     *ICOPY
  434.  
  435. To connect at the default baud rate (9600 baud), ensure the lead is
  436. connected correctly, enter the BBCEmulator, and type
  437.  
  438.     *CONNECT
  439.  
  440. This will prompt you to enter a command at the BBC end (*FX 2,1), then
  441. press any key on Amiga.  Connection will then either then proceed ok, and
  442. the BBC will print a message indicating that it is under remote control
  443. from the Amiga, or it will fail - eg because the lead isn't right - and
  444. the Amiga will print "Connect failed".  Connection can be terminated by
  445. pressing ESC.
  446.  
  447. To connect at a different baud rate - eg 1200 baud, type
  448.  
  449.     *CONNECT 1200
  450.  
  451. then follow the instructions printed.  Baud rates supported are 150, 300,
  452. 1200, 2400, 4800, 9600 and 19200, though the last is NOT guaranteed - indeed
  453. it doesn't work properly at the moment!
  454.  
  455. Note that use of the lower baud rates MIGHT allow *CONNECT to be used over
  456. a modem link.  This is not recommended however except over error correcting
  457. modems, as the error checking in the program itself is only very simple.
  458.  
  459. To disconnect "politely" and free the remote machine, enter
  460.  
  461.     *SEVER
  462.  
  463. To disconnect "rudely" perform a BREAK (left-Amiga HELP) on the BBCEmulator.
  464. The far end will then have to be manually reset by pressing BREAK.
  465.  
  466. Having connected, it is then possible to copy files.  To copy an entire disk
  467. from remote drive 1 to BBCEmulator drive 0 use
  468.  
  469.     *IMPORT 1 0
  470.  
  471. Note that this will erase the previous contents of BBCEmulator drive 0.  More
  472. generally, use
  473.  
  474.     *IMPORT    <remote source drive> <BBCEmulator destination drive>
  475.  
  476. To copy files selectively, use *ICOPY.  To copy files from directory B on
  477. remote drive 1 to BBCEmulator drive 0 use
  478.  
  479.     *ICOPY 1 0 B.*
  480.  
  481. More generally, the syntax is
  482.  
  483.     *ICOPY <source> <destination> <files>
  484.  
  485. where <files> is an Ambiguous File Specification as used by *COPY.
  486.  
  487. IMPORT or ICOPY can be terminated politely by pressing ESC, which will cause
  488. termination after the current file has been completed, or rudely by pressing
  489. BREAK (left-Amiga HELP), which will terminate immediately.  In the latter
  490. case, it will be necessary to reset the remote machine (press BREAK) then
  491. reconnect before trying again.
  492.  
  493. NOTE that IMPORT and ICOPY are designed to work with standard DFS on the
  494. remote machine.  Non-standard systems are not guaranteed to work correctly.
  495.  
  496. Boot facilities
  497. ~~~~~~~~~~~~~~~
  498. If you are using the system's default ASSIGNs, then having imported a disk
  499. to drive 0, you can then "boot" the disk by the special command
  500.  
  501.     *BOOT 0
  502.  
  503. Alternatively, you can both invoke the BBCEmulator and auto-boot the disk
  504. by double-clicking on the corresponding "5 1/4 disk" icon on the Amiga 
  505. Workbench.  This will start the BBCEmulator and boot the disk.  As soon as the
  506. application is finished - at the point where it would return to the BASIC 
  507. '>' prompt - the BBCEmulator will exit back to the Amiga Workbench.
  508.  
  509. Techy note - More about booting
  510. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  511. Readers reasonably familiar with the Amiga may appreciate the following
  512. additional information about booting:
  513.  
  514. The "5 1/4 disk" Icons are Amiga project Icons, set with stack size 16000, and
  515. Default Tool = BBCEmulator.  You can use IconEd, or various public domain Icon
  516. edit tools to create custom imagery for boot icons for particular programs.
  517.  
  518. The effect of double clicking on a 5 1/4 disk icon "Boot1" (or whatever) is in
  519. fact to force the BBCEmulator automatically to AExec file "Boot1" on entry.
  520. The default contents of this file are:
  521.  
  522.     *FORCECLOSE
  523.     *ASSIGN 0 DRIVE1
  524.     *BOOT 0
  525.  
  526. but you can change this for special purposes using an editor like Emacs.  The
  527. trick of forcing the BBCEmulator to close down instead of returning to BASIC 
  528. '>' prompt (or CLI environment '*' prompt) is achieved using the special
  529. command
  530.  
  531.     *FORCECLOSE
  532.  
  533. Note that if a *FORCECLOSE has been performed, then an ordinary BREAK (LEFT-
  534. AMIGA-HELP) will exit the BBCEmulator.  However, a hard break (CTRL-LEFT-
  535. AMIGA-HELP) will override *FORCECLOSE, and stay in the system.
  536.  
  537. It is also possible to run the BBCEmulator from the Amiga CLI environment,
  538. using a command such as
  539.  
  540.     BEEB BOOT0
  541.  
  542. where "BOOT0" is the name of a file to AExec on entry.  NOTE that in order
  543. to do this, you should first CD to the directory containing the BBCEmulator
  544. and BASIC (or the system won't find BASIC); you should also set the stack
  545. to at least 16000 using the STACK command.  Reader's familiar with the
  546. Amiga's s:startup-sequence will realize that it is therefore possible to
  547. create a "turnkey" disk, that will automatically boot a BBCEmulator
  548. application after a disk is inserted on the power-up prompt for Workbench.
  549.  
  550. BBC BASIC
  551. ~~~~~~~~~
  552. BBCEmulator BASIC is a new version of BBC BASIC, coded in 68000 assembler.
  553. Keywords supported are as follows:
  554.  
  555.     ABS        ACS        ADVAL        AND
  556.     ASC        ASN        ATN        AUTO
  557.     BGET        BPUT        CALL        CHAIN
  558.     CHR$        CLEAR        CLG        CLOSE
  559.     CLS        COLOUR        COS        COUNT
  560.     DATA        DEF        DEG        DELETE
  561.     DIM        DIV        DRAW        ELSE
  562.     END        ENDPROC        ENVELOPE    EOF
  563.     EOR        ERL        ERR        ERROR
  564.     EVAL        EXP        EXT        FALSE
  565.     FN        FOR        GCOL        GET
  566.     GET$        GOSUB        GOTO        HIMEM
  567.     IF        INKEY        INKEY$        INPUT
  568.     INSTR(        INT        LEFT$(        LEN
  569.     LET        LINE        LIST        LN
  570.     LOAD        LOCAL        LOG        LOMEM
  571.     MID$(        MOD        MODE        MOVE
  572.     NEW        NEXT        NOT        OFF
  573.     OLD        ON        OPENIN        OPENOUT
  574.     OPENUP        OR        OSCLI        PAGE
  575.     PAGE        PI        PLOT        POINT(
  576.     POS        PRINT        PROC        PTR
  577.     RAD        READ        REM        RENUMBER
  578.     REPEAT        REPORT        RESTORE        RETURN
  579.     RIGHT$(        RND        RUN        SAVE
  580.     SGN        SIN        SOUND        SPC
  581.     SQR        STEP        STOP        STR$
  582.     STRING$(    TAB(        TAN        THEN
  583.     TIME        TO        TRACE        TRUE
  584.     UNTIL        USR        VAL        VDU
  585.     VPOS        WIDTH
  586.  
  587. The only areas of possible difficulty are as follows:
  588.  
  589. Floating Point Precision - The BBCEmulator uses the Amiga's "fast floating
  590. point" maths routines - these are VERY fast, but work to only four bytes
  591. precision, as opposed to five bytes on the BBC.  The default value of
  592. @% is therefore set to &060A as opposed to &090A, giving six rather than
  593. nine decimal places of accuracy.
  594.  
  595. CALL with parameters - The simple cases of CALL (eg CALL P%, CALL &3000)
  596. work fine; the exotic cases where CALL is passed a list of variables are
  597. however not supported, and give an error message "Not implemented".
  598. This is because 68000 BBC BASIC uses a different internal variables
  599. representation to the 6502 version.
  600.  
  601. ENVELOPE - Passed to the OS, but not yet implemented.
  602.  
  603. ADVAL command - always returns zero.
  604.  
  605. Negative INKEY - always returns zero.
  606.  
  607. GCOL modes 1 to 4 - not supported by the OS.
  608.  
  609. 6502 Monitor
  610. ~~~~~~~~~~~~
  611. A simple 6502 monitor is included, loosely based on the old PET monitors like
  612. Supermon!  Entry is via *MONITOR; commands are
  613.  
  614.     *    execute CLI command
  615.     Q    exit monitor
  616.     M    display memory
  617.     .    alter memory
  618.     R    display registers
  619.     ;    alter registers
  620.     D    disassemble
  621.     G    go
  622.  
  623. Commands are typically followed by one or more hex parameters, eg
  624.  
  625.     M 0000 0100    display page zero
  626.     M 0200        display block from $0200
  627.     M        display next block
  628.     D 8000 8020    disassemble from $8000 to $8020
  629.     D A000        disassemble next block from $A000
  630.     D        disassemble next block
  631.     G 8000        execute from $8000
  632.     G        execute from current PC
  633.  
  634. '.' and ';' are designed so that register and memory contents can be
  635. changed by cursoring up, then using the copy key from the start of the
  636. line in question.
  637.  
  638. Operating system
  639. ~~~~~~~~~~~~~~~~
  640. Calls currently supported under the 6502 emulator are as follows:
  641.  
  642.     GSINIT    -    Fully supported
  643.     GSREAD    -    Fully supported
  644.  
  645.     OSFIND    -    All DFS compatible options
  646.     OSGBPB  -    All DFS compatible options
  647.     OSBPUT    -    Fully supported
  648.     OSBGET    -    Fully supported
  649.     OSARGS    -    All DFS compatible options
  650.     OSFILE    -    All DFS compatible options
  651.     OSRDCH    -    Keyboard or exec file only
  652.     OSASCI    -    Fully supported
  653.     OSNEWL    -    Fully supported
  654.     OSWRCH  -    Screen or spool file only
  655.     OSWORD    -    Nearly all calls supported
  656.     OSBYTE  -    Major calls supported
  657.     OSCLI     -    Fully supported
  658.  
  659. Indirection via the Page 2 vectors is NOT properly supported under version
  660. 0.95.
  661.  
  662. OSBYTE calls supported are as follows:
  663.  
  664.     OSBYTE &00 Identify Operating System Version
  665.     OSBYTE &01 Read/write the user flag - NOT YET
  666.     OSBYTE &02 Select input stream - NOT YET
  667.     OSBYTE &03 Select output stream - NOT YET
  668.     OSBYTE &04 Enable/disable cursor editing
  669.     OSBYTE &06 Set character ignored by printer - NOT YET
  670.     OSBYTE &07 Set RS423 baud rate for receiving data - NOT YET
  671.     OSBYTE &08 Set RS423 baud rate for transmitting data - NOT YET
  672.     OSBYTE &09 Set duration of the mark state of flashing colours
  673.     OSBYTE &0A Set duration of the space state of flashing colours
  674.     OSBYTE &0F Flush selected buffer class
  675.     OSBYTE &12 Reset soft keys
  676.     OSBYTE &13 Wait for vertical sync - NOT YET
  677.     OSBYTE &14 Explode soft character RAM allocation
  678.     OSBYTE &15 Flush selected buffer
  679.     OSBYTE &77 Close any SPOOL or EXEC files
  680.     OSBYTE &7C Clear ESCAPE condition
  681.     OSBYTE &7D Set Escape condition
  682.     OSBYTE &7E Acknowledge detection of an ESCAPE condition
  683.     OSBYTE &7F Check for end-of-file on an opened file
  684.     OSBYTE &81 Read key with time limit
  685.     OSBYTE &82 Read machine high order address
  686.     OSBYTE &83 Read top of operating system RAM address (OSHWM)
  687.     OSBYTE &84 Read bottom of display RAM address (OSLWM)
  688.     OSBYTE &85 Read bottom of display RAM address for a specified mode
  689.     OSBYTE &86 Read text cursor position (POS and VPOS)
  690.     OSBYTE &87 Read character at text cursor position - NOT YET
  691.     OSBYTE &88 Execute code indirected via USERV - NOT YET
  692.     OSBYTE &91 Get character from buffer - NOT YET
  693.     OSBYTE &DA Read/write number of items in VDU queue
  694.     OSBYTE &E1 Read/write function key status
  695.     OSBYTE &E2 Read/write SHIFT+function key status
  696.     OSBYTE &E3 Read/write CTRL+function key status
  697.     OSBYTE &E4 Read/write CTRL+SHIFT+function key status
  698.     OSBYTE &E5 Read/write status of ESCAPE key
  699.     OSBYTE &E6 Read/write ESCAPE effects
  700.  
  701. OSWORD calls supported are as follows:
  702.  
  703.     OSWORD &00 Read line from input stream to memory
  704.     OSWORD &01 Read system clock
  705.     OSWORD &02 Write system clock
  706.     OSWORD &03 Read interval timer
  707.     OSWORD &04 Write interval timer
  708.     OSWORD &07 Generate a sound
  709.     OSWORD &08 Define an envelope - NOT YET
  710.     OSWORD &09 Read pixel colour
  711.     OSWORD &0A Read character definition
  712.     OSWORD &0B Read the VDU palette
  713.     OSWORD &0C Write the VDU palette - NOT YET
  714.     OSWORD &0D Read current/previous graphics cursor position - NOT YET
  715.